home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / gnustuff / tos / othergnu / gdbm15.zoo / gdbm.3 < prev    next >
Encoding:
Text File  |  1992-09-24  |  10.0 KB  |  315 lines
  1.  
  2. NAME
  3.     gdbm - GNU database routines
  4.  
  5. SYNOPSIS
  6.     #include <gdbm.h>
  7.     
  8.     GDBM_FILE gdbm_open(name, block_size, read_write, mode, fatal_func)
  9.         char *name;
  10.         int block_size;
  11.         int read_write;
  12.         int mode;
  13.         void (*fatal_func)();
  14.     
  15.     void gdbm_close(dbf)
  16.         GDBM_FILE dbf;
  17.     
  18.     int gdbm_store(dbf, key, content, flags)
  19.         GDBM_FILE dbf;
  20.         datum key;
  21.         datum content;
  22.         int flags;
  23.     
  24.     datum gdbm_fetch(dbf, key)
  25.         GDBM_FILE dbf;
  26.         datum key;
  27.     
  28.     int gdbm_delete(dbf, key)
  29.         GDBM_FILE dbf;
  30.         datum key;
  31.     
  32.     datum gdbm_firstkey(dbf)
  33.         GDBM_FILE dbf;
  34.     
  35.     datum gdbm_nextkey(dbf, key)
  36.         GDBM_FILE dbf;
  37.         datum key;
  38.     
  39.     int gdbm_reorganize(dbf)
  40.         GDBM_FILE dbf;
  41.  
  42. DESCRIPTION
  43.     This is  release  1.5  of GNU dbm.  Also included is support for
  44.     standard UNIX dbm(3x) and ndbm(3).  For  information  on  these,
  45.     see the corresponding documentation.
  46.  
  47.     GNU  dbm is a set of database routines that use extendible hash-
  48.     ing and works similar to the standard UNIX dbm  routines.    The
  49.     basic unit of data is the structure:
  50.  
  51.         typedef struct {
  52.             char *dptr;
  53.             int   dsize;
  54.         } datum;
  55.  
  56.     An  include  file  will  be produced that can be included by the
  57.     user.  The file is ``gdbm.h''. ``dbm.h'' and ``ndbm.h'' are also
  58.     provided if they are not already available.
  59.  
  60.     GNU dbm allows multiple data files.  A routine that opens a gdbm
  61.     file is designated as a "reader" or a "writer". Only one  writer
  62.     may  open  a  gdbm  file  and  many  readers  may open the file.
  63.     Readers and writers can not open  the  gdbm  file  at  the  same
  64.     time.  The procedure for opening a gdbm file is:
  65.  
  66.         GDBM_FILE dbf;
  67.     
  68.         dbf = gdbm_open(name,block_size,read_write,mode,fatal_func)
  69.  
  70.     The parameters are:
  71.  
  72.     char *name
  73.         the  name  of the file (the complete name, gdbm does not
  74.         append any characters to this name)
  75.  
  76.     int block_size
  77.         the size of a single transfer from disk to memory.  This
  78.         parameter is ignored unless the file is a new file.  The
  79.         minimum size is 512. If it is less than  512,  dbm  will
  80.         use the stat block size for the file system.
  81.  
  82.     int read_write
  83.         0  =>  reader, 1 => writer, 2 => writer (if the database
  84.         does not exist, create a new one, 3 => writer and create
  85.         a new database regardless if one exists.    (Defined  in
  86.         gdbm.h   as   GDBM_READER,   GDBM_WRITER,  GDBM_WRCREAT,
  87.         GDBM_NEWDB.)
  88.  
  89.     int mode
  90.         file mode (see chmod(2) and  open(2))  if  the  file  is
  91.         created.
  92.  
  93.     void (*fatal_func)()
  94.         a  function for dbm to call if it detects a fatal error.
  95.         The only parameter of this function is a string.  If the
  96.         value  of  0  is  provided,  gdbm  will  use  a  default
  97.         function.
  98.  
  99.     The  return  value,  dbf,  is  the  pointer  needed by all other
  100.     routines to access that gdbm file.  If the return  is  the  NULL
  101.     pointer, gdbm_open  was not successful.  The errors can be found
  102.     in "gdbm_errno" for gdbm errors and in "errno" for  file  system
  103.     errors.  (For error codes, see gdbmerrno.h.)
  104.  
  105.     In all of the following calls, the parameter "dbf" refers to the
  106.     pointer returned from gdbm_open.
  107.  
  108.     It is  important that every file opened is also closed.  This is
  109.     needed to update the reader/writer count on the file.   This  is
  110.     done by:
  111.  
  112.         gdbm_close(dbf);
  113.  
  114.     The database  is  used  by 3 primary routines.  The first stores
  115.     data in the database.
  116.  
  117.         ret = gdbm_store(dbf, key, content, flag)
  118.  
  119.     The parameters are:
  120.  
  121.     GDBM_FILE dbf
  122.         the pointer returned by gdbm_open
  123.  
  124.     datum key
  125.         the key data
  126.  
  127.     datum content
  128.         the data to be associated with the key
  129.  
  130.     int flag
  131.         0 => insert only, generate an error if key exists.  1 =>
  132.         replace contents if key exists.  (Defined in  gdbm.h  as
  133.         GDBM_INSERT and GDBM_REPLACE.)
  134.  
  135.         If  a  reader  calls  store, ret gets -1. If called with
  136.         GDBM_INSERT and key is in  the  database,  ret  gets  1.
  137.         Otherwise, ret  is  0.   NOTICE: If you store data for a
  138.         key that is already in the data base, gdbm replaces  the
  139.         old  data with the new data if called with GDBM_REPLACE.
  140.         You do not get two data items for the same key  and  you
  141.         do not  get  an error from gdbm_store.  NOTICE: The size
  142.         in gdbm is not restricted like dbm or ndbm.   Your  data
  143.         can be  as  large  as your "want".  NOTICE: Both key and
  144.         content must have the dptr field be  a  non-NULL  value.
  145.         Since  a  NULL  dptr  field is used by other routines to
  146.         indicate an error, a NULL field cannot  be  valid  data.
  147.         If  either  key  or  content  have  a  null  dptr field,
  148.         gdbm_open will return an error.
  149.  
  150.     To search for some data:
  151.  
  152.         content = gdbm_fetch(dbf, key)
  153.  
  154.     The parameters are:
  155.  
  156.     GDBM_FILE dbf
  157.         the pointer returned by gdbm_open
  158.  
  159.     datum key
  160.         the key data
  161.  
  162.         The "datum" returned in content is a pointer to the data
  163.         found.  If the dptr is NULL, no data was found.  If dptr
  164.         is not  NULL,  then  it  points  to  data  allocated  by
  165.         malloc.   gdbm  does  not  automatically free this data.
  166.         The user must free this  storage  when  done  using  it.
  167.         This  eliminates  the need to copy the result to save it
  168.         for later use.  (You just save the pointer.)
  169.  
  170.     To remove some data from the database:
  171.  
  172.         ret = gdbm_delete(dbf, key)
  173.  
  174.     The parameters are:
  175.  
  176.     GDBM_FILE dbf
  177.         the pointer returned by gdbm_open
  178.  
  179.     datum key
  180.         the key data
  181.  
  182.         The ret value is -1 if the item is not  present  or  the
  183.         requester is  a reader.  The ret value is 0 if there was
  184.         a successful delete.
  185.  
  186.     The next two routines allow  for  accessing  all  items  in  the
  187.     database.   This access is not key sequential, but it is guaran-
  188.     teed to visit every key in the database once.  (The order has to
  189.     do with the hash values.)
  190.  
  191.         key = gdbm_firstkey(dbf)
  192.     
  193.         nextkey = gdbm_nextkey(dbf, key)
  194.  
  195.     The parameters are:
  196.  
  197.     GDBM_FILE dbf
  198.         the pointer returned by gdbm_open
  199.     datum key
  200.         the key data
  201.  
  202.         The return values  are  both  datum.    If  key.dptr  or
  203.         nextkey.dptr  is  NULL,  there  is  no first key or next
  204.         key.  Again notice that dptr points to data allocated by
  205.         malloc and gdbm will not free it for you.
  206.  
  207.     The following routine should be used very seldom.
  208.  
  209.         ret = gdbm_reorganize(dbf);
  210.  
  211.     If you have had a lot of deletions and would like to shrink  the
  212.     space  used  by  the gdbm file, the this routine will reorganize
  213.     the database.  gdbm will not shorten the length of a  gdbm  file
  214.     except by  using  this reorganization.  (Deleted file space will
  215.     be reused.)
  216.  
  217.     The following two are variables that may need to be used:
  218.  
  219.     gdbm_error gdbm_errno
  220.         the variable that contains more information  about  gdbm
  221.         errors.   (gdbm.h  has  the  definitions  of  the  error
  222.         values.)
  223.  
  224.     char *gdbm_version
  225.         the string containing the version information.
  226.  
  227.     There are a few more things of interest.  First, gdbm files  are
  228.     not  "sparse".  You  can  copy them with the UNIX cp command and
  229.     they will not expand in the copying process.  Also, there  is  a
  230.     compatibility  mode  for use with programs that already use UNIX
  231.     dbm.  In this compatibility mode, no gdbm file  pointer  is  re-
  232.     quired by the user.  Only one file may be opened at a time.  All
  233.     users in  compatibility  mode are assumed to be writers.  If the
  234.     gdbm file is a read only, it will fail as  a  writer,  but  will
  235.     also try to open it as a reader.  All returned pointers in datum
  236.     structures point  to  data  that gdbm WILL free.  They should be
  237.     treated as static pointers (as standard UNIX dbm does).
  238.  
  239. SEE ALSO
  240.     dbm(3x), ndbm(3),conv2gdbm(1)
  241.  
  242. NOTES
  243.     If you port gdbm to another system, try  to  follow  the  change
  244.     style used  for  System  V changes.  Please send your changes to
  245.     phil@cs.wwu.edu if you would like your  changes  included  in  a
  246.     future release of gdbm.
  247.  
  248.     Please send bug reports to bug-gnu-utils@prep.ai.mit.edu.
  249.  
  250. COMPATIBILITY
  251.     NOTE:  Some  implementations  have an include file "dbm.h". That
  252.     file is just a file that defines datum and the  above  routines.
  253.     Many original  dbm  sites  do  not  have a "dbm.h" file.  One is
  254.     included here for those who want it.
  255.  
  256.     WARNING: standard UNIX dbm and GNU dbm do not have the same data
  257.     format in the file.  You cannot access a standard UNIX dbm  file
  258.     with GNU  dbm!  If you want to use an old database with GNU dbm,
  259.     you must use the convert program.
  260.  
  261.     Also, GNU dbm has compatibility routines for  ndbm.    For  ndbm
  262.     compatiblity routines, you need the include file "ndbm.h".
  263.  
  264.     WARNING:  If  you have ndbm and gdbm, there is a conflict in the
  265.     names of the  include  file  for  the  ndbm  interface  and  the
  266.     original ndbm  package.    Do  not blindly copy "ndbm.h" to your
  267.     include directory.
  268.  
  269.     For compatibility with the standard dbm, the following  routines
  270.     are defined.    There  is  an  include file for dbm users called
  271.     ``dbm.h''.
  272.  
  273.         int dbminit(name)
  274.     
  275.         int store(key, content)
  276.     
  277.         datum fetch(key)
  278.     
  279.         int delete(key)
  280.     
  281.         datum firstkey()
  282.     
  283.         datum nextkey(key)
  284.  
  285.     There are also compatibility routines for ndbm.  For  ndbm  com-
  286.     patiblity routines,  you  need the include file ``ndbm.h''.  The
  287.     routines are:
  288.  
  289.         DBM *dbm_open(name, flags, mode)
  290.     
  291.         void dbm_close(file)
  292.     
  293.         datum dbm_fetch(file, key)
  294.     
  295.         int dbm_store(file, key, content, flags)
  296.     
  297.         int dbm_delete(file, key)
  298.     
  299.         datum dbm_firstkey(file)
  300.     
  301.         datum dbm_nextkey(file)
  302.     
  303.         int dbm_error(file)
  304.     
  305.         int dbm_clearerr(file)
  306.     
  307.         int dbm_pagfno(file)
  308.     
  309.         int dbm_dirfno(file)
  310.  
  311.     Again, just like ndbm, any returned datum can be assumed  to  be
  312.     static storage.    You do not have to free that memory, the ndbm
  313.     compatibility routines will do it for you.
  314.  
  315.